/*
 * Copyright 2004 original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.jbfilter.bean;

import java.util.Collection;
import java.util.List;

import org.jbfilter.core.Filter;

/**
 * The filter contract for JVM side filtering (in memory filtering).
 * @author Marcus Adrian
 * @param <E> for type safety the filter must be parameterized with the type of the beans to filter.
 */
public interface FilterBean<E> extends Filter<E> {
	/**
	 * Filters the collection. Calls {@link FilterComponentBeanSpecific#filterOut(java.util.LinkedList)} on all the
	 * {@link FilterComponentBeanSpecific}s which where added to this filter. However only {@link FilterComponentBeanSpecific}s
	 * which are enabled will take effect.
	 * <p>
	 * The original collection passed in as a parameter is NOT modified.
	 * Instead a new collection (a list) of the elements which passed the filter is returned.
	 * Returning a list ensures that ordering will be preserved if the passed in collection was
	 * ordered.
	 * @param toFilter the collection to filter
	 * @return the elements which passed the filter
	 */
	List<E> filter(Collection<E> toFilter);
	/**
	 * Facility method. Calls {@link #filter(Collection)} internally.
	 * @see {@link #filter(Collection)}
	 */
	List<E> filter(E[] toFilter);
	@Override
	FilterHandlerBean<E> newFilterHandler();
	/**
	 * Indicates if this single bean passes the filter.
	 * @param bean the bean to test
	 * @return  {@code true} if the bean passes the filter, otherwise {@code false}.
	 */
	boolean pass(E bean);

}
